Batch saas synchronous api 2#266
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
mnemitz
left a comment
mnemitz
left a comment
There was a problem hiding this comment.
Looks good, just a few minor questions/suggestions!
| @@ -0,0 +1,120 @@ | |||
| --- | |||
| description: 'Block for a transcript in a single request instead of polling for job status.' | |||
There was a problem hiding this comment.
Personal opinion, but I find something like this clearer:
| description: 'Block for a transcript in a single request instead of polling for job status.' | |
| description: Wait for a transcription job to finish synchronously via HTTP |
| The `wait` query parameter blocks a request until the job reaches a terminal state, so you can get a transcript in one call instead of polling. It applies to job creation, job status, and transcript retrieval. | ||
|
|
||
| :::info | ||
| `wait` is available on SaaS on Cloud only. It is not available on on-prem deployments. |
There was a problem hiding this comment.
To me this sounds like we'll never offer it, what do you think?
| `wait` is available on SaaS on Cloud only. It is not available on on-prem deployments. | |
| `wait` is available on SaaS on Cloud only. It is not currently available on on-prem deployments. |
|
|
||
| ## Create a job and wait for the transcript | ||
|
|
||
| Pass `wait` to `POST /jobs` to block until the job finishes. Add `format` to choose the embedded transcript format (`json-v2`, `txt`, or `srt`; defaults to `json-v2`). |
There was a problem hiding this comment.
| Pass `wait` to `POST /jobs` to block until the job finishes. Add `format` to choose the embedded transcript format (`json-v2`, `txt`, or `srt`; defaults to `json-v2`). | |
| Pass the `wait` query parameter to `POST /jobs` to block until the job finishes. Add `format` to choose the embedded transcript format (`json-v2`, `txt`, or `srt`; defaults to `json-v2`). |
|
|
||
| # Synchronous transcription | ||
|
|
||
| The `wait` query parameter blocks a request until the job reaches a terminal state, so you can get a transcript in one call instead of polling. It applies to job creation, job status, and transcript retrieval. |
There was a problem hiding this comment.
I think it's good to spell out the full breadth of the feature from the top for clarity. Maybe something like this:
| The `wait` query parameter blocks a request until the job reaches a terminal state, so you can get a transcript in one call instead of polling. It applies to job creation, job status, and transcript retrieval. | |
| The `wait` query parameter lets you block a job request until either: | |
| - The job enters a terminal state (`done` or `rejected`) | |
| - The specified number of seconds elapses. | |
| This allows you to avoid polling the API for job completion. The `wait` parameter can be used for several endpoints: i.e. creating a job, fetching job details, and fetching the full transcript. |
| } | ||
| ``` | ||
|
|
||
| `status` reports the outcome of the wait, which is distinct from the [job lifecycle status](/speech-to-text/batch/output#check-single-job-status): |
There was a problem hiding this comment.
I'm a bit confused about this, I thought status would always return the current status of the job? Or is it just in the case of created after wait that it may be different?
| description: >- | ||
| **Note**: Only available on SaaS on Cloud. | ||
|
|
||
| Number of seconds to block until the job reaches a terminal state before responding. Capped server-side. When set, the response includes a `status` field reporting the outcome, and on `done` the transcript is embedded under the requested `format` key when available. When omitted, the request returns as soon as the job is created and `status` is not included. |
There was a problem hiding this comment.
If I remember correctly there is a possibility of timeout if someone specifies a very long wait time (like several hours). Is it worth communicating an upper limit either in the spec or in the doc page?
| <br/> | ||
| To get a transcript in a single blocking call instead of polling, see [Synchronous transcription](/speech-to-text/batch/synchronous). |
There was a problem hiding this comment.
Two small things on this tip block:
-
Avoid
<br/>inside an admonition. It's fragile MDX — the new sentence hangs in the tip without paragraph spacing. Cleaner as two separate paragraphs (blank line between them), or split into two admonitions::::infofor "you can also block with synchronous mode" (a routing hint rather than a tip), and keep:::tipfor the notifications mention. -
The intro at line 22 ("Transcription jobs are processed asynchronously…") now reads as half-true given this PR ships a blocking option. Suggest softening to "Transcription jobs are processed asynchronously by default…" or rephrasing to acknowledge both polling and the new synchronous option.
(Refs: style guide — admonition usage; AI-readability — opening sentence names the subject accurately.)
| --- | ||
| description: 'Block for a transcript in a single request instead of polling for job status.' | ||
| --- |
There was a problem hiding this comment.
Missing title: in the frontmatter — only description: is set. The style guide requires both title and description on every page (AI-readability standards). Docusaurus falls back to the H1, so the page currently renders fine, but explicit frontmatter keeps search, retrieval, and page metadata consistent across the site.
Suggest:
---
title: Synchronous transcription
description: Block for a transcript in a single request instead of polling for job status.
---
|
One follow-up not in this diff: No need to expand the scope of this PR — happy for it to be a separate follow-up if you'd rather keep this one focused on the Batch section. |
3 participants
Summary
Documents the new synchronous Batch API, which lets clients block for a job result via a wait query parameter
instead of polling. Covers all three affected endpoints and adds a task-oriented how-to page. SaaS on Cloud only.
Changes
API reference (spec/batch.yaml)
query params. Extended CreateJobResponse with an opt-in status field (created | done | rejected | deleted) and
json-v2/txt/srt keys carrying the embedded transcript. status is present only when wait is set, so the schema stays
backward-compatible.
otherwise the usual 404; retryable.
Docs
status outcome table, and the best-effort embedded-transcript fallback.